# -*- coding: utf-8 -*-
"""
Base classes for QA retrieval retrievers

This module defines the abstract base interface that all retrievers must implement.
"""

from abc import ABC, abstractmethod
from typing import List, Dict, Tuple, Union, Optional
import numpy as np


class BaseRetriever(ABC):
    """
    Abstract base class for all question retrievers.
    
    This class defines the standard interface that all retriever implementations
    must follow to ensure consistency across different approaches.
    """
    
    @abstractmethod
    def load_candidates(self, questions: List[str], scores: List[float] = None):
        """
        Load candidate questions for recommendation.
        
        Args:
            questions: List of candidate questions
            scores: Optional scores for each question
        """
        pass
    
    @abstractmethod
    def recommend(self, query_question: str, top_k: int = 5, **kwargs) -> List[Tuple]:
        """
        Recommend similar questions for a given query.
        
        Args:
            query_question: The input question to find recommendations for
            top_k: Number of recommendations to return
            **kwargs: Additional method-specific parameters
            
        Returns:
            List of tuples containing recommended questions and scores
        """
        pass
    
    def batch_recommend(self, queries: List[str], top_k: int = 5) -> Dict[str, List[Tuple]]:
        """
        Batch recommendation for multiple queries.
        
        Default implementation calls recommend() for each query.
        Subclasses can override for more efficient batch processing.
        
        Args:
            queries: List of query questions
            top_k: Number of recommendations per query
            
        Returns:
            Dictionary mapping queries to their recommendations
        """
        results = {}
        for query in queries:
            results[query] = self.recommend(query, top_k)
        return results